Python: resolve forward references nested in generic aliases when building schemas - #14310

Motivation and Context

Fixes #14239

A string forward reference inside a generic alias, such as list["Inner"], dict[str, "Inner"] or list[list["Inner"] | None], is never resolved to the class it names. On a kernel function the same goes for Optional["Inner"], Union["Inner", None] and Annotated["Inner", ...], which unwrap to a bare ForwardRef. The schema built for it is the bare {"type": "object"} placeholder with no properties and no required list. That schema is what the model receives as a function calling parameter definition, so a plugin written this way hands the model an untyped blob for that argument without any error or warning. A top level "Inner" already works, which makes the gap easy to miss.

Two entry points are affected, and they differ by Python version:

Why the decorator path is broken on every version. kernel_function_decorator._process_signature reads annotations from inspect.signature(func, eval_str=True). eval_str evaluates an annotation that is itself a string, but not a string nested inside an alias that already exists as an object. type_object therefore reaches KernelJsonSchemaBuilder.build as list['Inner'] with the bare str still in __args__. handle_complex_type then calls build("Inner"), which takes the isinstance(parameter_type, str) branch and falls through build_from_type_name to the placeholder. In the bare ForwardRef cases invoking the function also fails, with Parameter x is expected to be parsed to ForwardRef('Inner') but is not.

class P:
    @kernel_function(name="fwd")
    def fwd(self, items: list["Inner"]) -> str: ...

KernelFunction.from_method(P().fwd).metadata.parameters[0].schema_data
# before: {"type": "array", "items": {"type": "object"}}
# after:  {"type": "array", "items": {"type": "object", "properties": {"value": ..., "label": ...}, "required": [...]}}

Why the model field path is 3.10 only. build_model_schema goes through get_type_hints, which on 3.10 evaluates ForwardRef objects nested inside an alias but not bare strings. list.__class_getitem__ stores "Inner" verbatim with no ForwardRef wrapper:

# Python 3.10
get_type_hints(HolderFwd)["items"]   # list['Inner']   the str survives
# Python 3.11 and later
get_type_hints(HolderFwd)["items"]   # list[Inner]     resolved

Python 3.11 changed get_type_hints to wrap those strings itself (CPython issue 85542, listed in the 3.11 What's New under typing). 3.10 is still inside requires-python = ">=3.10" and is a first class leg of the python-unit-tests.yml matrix, so the placeholder is what 3.10 users ship today.

Description

• KernelJsonSchemaBuilder.resolve_forward_refs(annotation, globalns), new and public. Resolves str and ForwardRef references against a namespace, bare or at any depth. PEP 604 unions are rebuilt with reduce(or_, args), as typing._eval_type does, because types.UnionType is not subscriptable. Callable parameter lists, ClassVar and Final are handled too. Literal members and Annotated metadata are left alone, since those strings are values rather than names.
• What stays a placeholder. A name that cannot be resolved is left as it is, keeping the previous placeholder rather than raising. The same goes, with a warning, for a reference to a class whose own hints do not evaluate, which would otherwise raise at registration. A rebuild that fails logs a warning and keeps the alias.
• build_model_schema applies it against the model's module globals, which are already fetched a few lines above for the get_type_hints call. On 3.11 and later model field hints arrive resolved and the resolver returns them unchanged. It also returns the placeholder for a model already being built further up the call stack; see the next section.
• _process_signature gains an optional globalns. The decorator passes func.__globals__ and each parameter's type_object is resolved before it is stored. Callers that pass nothing get the previous behaviour; the existing _process_signature(func_sig) tests are untouched.

Return type annotations are deliberately out of scope. -> list[Inner] already collapses to a bare list type_object today regardless of forward references, which is a separate limitation.

Relationship to #14198. This overlaps it in one place. Once references resolve, a self referencing model such as a kernel function parameter typed list["Node"] recurses where main stopped at a placeholder, so this PR needs a guard in build_model_schema. #14198 fixes the same RecursionError in the same function with $ref and $defs, which keeps the shape of the cycle where this guard cuts it off. Whichever lands second has to be reconciled, and the $ref design can replace the guard outright. Everything else here fires on a plain list["Inner"] with no recursion at all. As the issue notes, it is also why two of the new tests in #14198 fail on 3.10: TreeNode and Author/Book reach their cycles through list[...], so the string never resolves to a class and the cycle detection never engages.

Known limits, all the same as main. These stay a placeholder: a string expression such as list["list[Inner]"], an alias whose value holds a string, a class defined after the decorated function, and a function wrapped with functools.wraps from another module, because the namespace comes from the wrapper. list[list[Inner] | None] gets a correct schema but still cannot be invoked with a value, with or without forward references, because _parse_parameter calls the union.

Known differences from main. list["Good"] raises at registration where main gave the placeholder if the builder cannot build Good, for example when Good refers directly to a class whose hints do not evaluate. list[Good] raises the same way on main. typing.Sequence["Inner"], typing.Mapping[str, "Inner"] and similar aliases rebuild through collections.abc, so their placeholder becomes {"type": "object", "properties": {}}.

Testing plan

$ pytest tests/unit/schema tests/unit/functions/test_kernel_function_decorators.py

# Python 3.10.6
162 passed                                 (main: 92 passed)

# Python 3.13.15
161 passed, 1 skipped                      (main: 92 passed)

# Python 3.14.3
1 failed, 100 passed, 1 skipped, 1 error   (main: 1 failed, 57 passed, 1 error)

tests/unit/functions as a whole gives 232 passed on 3.10 and on 3.13. 3.11 and 3.12 were not run locally.

New tests against the source on main:

Removing any one of these parts of the builder fails tests on 3.10 and on 3.13: the union join, the single type forms, the Callable list, the rebuild warning, the recursion guard, the bare reference, the hints check and its warning.

One thing worth flagging: test_kernel_function_decorators.py does not collect on Python 3.14 on pristine main either (TypeError: 'member_descriptor' object is not iterable in _parse_parameter for any union annotation), and test_build_model_schema_class_var_via_instance fails there too. Those are the 1 error and 1 failure above. They are outside the CI matrix, so on 3.14 the resolver is covered through test_schema_builder.py only.

Lint and types: ruff check and ruff format --check pass on all four files with 0.9.6, the pre commit pin. mypy --config-file mypy.ini reports no issues in either changed source file.

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the SK Contribution Guidelines and the pre-submission formatting script raises no violations
• All unit tests pass, and I have added new tests where possible
• I didn't break anyone 😄